<!DOCTYPE html PUBLIC "-//IETF//DTD HTML 2.0//EN">
<!--

  	

  Copyright  2009  Sun Microsystems, Inc. All rights reserved.

-->
<html>
  <head>
    <title>I/O and Networking for the MID Profile</title>
    <!-- Changed  05-Feb-2002 -->
    <!-- Changed  08-Feb-2002 -->
    <!-- Changed 
    04-Mar-2002 -->
    <!-- Changed  10-Mar-2002 -->
    <!-- Changed  22-Apr-2002 -->
    <!-- Changed  09-Jul-2002 -->
    <!-- Changed 
    07-Aug-2002 -->
    <!-- Changed  03-Sep-2002 -->
  </head>

  <body>
    <p> MID Profile includes networking support based on the
      <code>Generic Connection</code> framework from the
      <em>Connected, Limited Device Configuration</em>.
    </p>


    <H2>HTTP Networking </H2>

    <p> In addition to the <code>javax.microedition.io</code>
      classes specified in the <em>Connected Limited Device
      Configuration</em> the <em>Mobile Information Device
      Profile</em> includes the following interface for the HTTP
      access. An <code>HttpConnection</code> is returned from
      <code>Connector.open()</code> when an <code>"http://"</code> connection 
      string is accessed.</p>

    <ul>
      <li><code>javax.microedition.io.HttpConnection</code></li>
    </ul>
    <P>
      The MIDP extends the connectivity support
      provided by the Connected, Limited Device Configuration (CLDC) with
      specific functionality for the 
      <EM>GenericConnection</EM>
      framework. The MIDP supports a subset of the HTTP protocol,
      which can be implemented using both IP protocols such as TCP/IP
      and non-IP protocols such as WAP and i-Mode, utilizing a gateway
      to provide access to HTTP servers on the Internet.</P>
    <P>
      The <EM>GenericConnection</EM>
      framework is used to support client-server and datagram
      networks. Using only the protocols specified by the MIDP will allow
      the application to be portable to all MIDs. MIDP implementations
      MUST provide support for accessing HTTP 1.1 servers and
      services.</P> 
    <P>
      There are wide variations in wireless
      networks. It is the joint responsibility of the device and the
      wireless network to provide the application service. It may require
      a <EM>gateway</EM>
      that can bridge between the wireless transports specific to the
      network and the wired Internet. The client application and the
      Internet server MUST NOT need to be required to know either that
      non-IP networks are being used or the characteristics of those
      networks. While the client and server MAY both take advantage of
      such knowledge to optimize their transmissions, they MUST NOT be
      required to do so.</P> 
    <P>
      For example, a MID MAY have no in-device
      support for the Internet Protocol (IP). In this case, it would
      utilize a gateway  to access the
      Internet, and the gateway would be responsible for some services,
      such as DNS name resolution for Internet URLs. The device and
      network may define and implement security and network access
      policies that restrict access.</P> 
      
    <H3>HTTP Network Connection</H3>
    <IMG SRC="doc-files/MIDP_Networking-4.gif" width=367 height=274>

    <P>
      The <EM>GenericConnection</EM>
      framework from the CLDC provides the base stream and content
      interfaces. The interface 
      <EM>HttpConnection</EM>
      provides the additional functionality needed to set request
      headers, parse response headers, and perform other HTTP specific
      functions. </P>

    <P>The interface MUST support:</P>
    <BLOCKQUOTE>
      HTTP 1.1
    </BLOCKQUOTE>
    <P>
      Each device implementing the MIDP
      MUST support opening connections using the following URL
      schemes (RFC2396 Uniform Resource Identifiers (URI): Generic
      Syntax)
    </P>

    <BLOCKQUOTE>
      &quot;http&quot; as defined by
      RFC2616 
      <EM>Hypertext Transfer Protocol --
	HTTP/1.1</EM>
    </BLOCKQUOTE>
    <P>
      Each device implementing the MIDP
      MUST support the full specification of RFC2616<BR>
      HEAD, GET and POST requests. The implementation MUST also
      support the absolute forms of URIs.</P>
    <P>
      The implementation MUST pass all
      request headers supplied by the application and response headers
      as supplied by the network server. The ordering of request and
      response headers MAY be changed. While the headers may be
      transformed in transit, they MUST be reconstructed as equivalent
      headers on the device and server. Any transformations MUST be
      transparent to the application and origin server. The HTTP
      implementation does not automatically include any headers. The
      application itself is responsible for setting any request
      headers that it needs.</P>
    <P>
      Connections may be implemented with
      any suitable protocol providing the ability to reliably
      transport the HTTP headers and data.(RFC2616 takes great
      care to not to mandate TCP streams as the only required
      transport mechanism.)  </P>

    <H3>HTTP Request Headers</H3>
    <P>
      The HTTP 1.1 specification provides a
      rich set of request and response headers that allow the
      application to negotiate the form, format, language, and other
      attributes of the content retrieved. In the MIDP, the
      application is responsible for selection and processing of
      request and response headers. Only the 
      <EM>User-Agent</EM>
      header is described in detail. Any other header that is mutually
      agreed upon with the server may be used.</P>
    
    <H3>User-Agent and Accept-Language Request Headers</H3>
    <P>
      For the MIDP, a simple 
      <EM >User-Agent</EM>
      field may be used to identify the current device. As specified
      by RFC2616, the field contains blank separated features where
      the feature contains a name and optional version number. </P>
    <P>
      The application is responsible for
      formatting and requesting that the 
      <EM>User-Agent</EM>
      field be included in HTTP requests via the 
      <EM>setRequestProperty</EM>
      method in the interface 
      <EM>javax.microedition.io.HttpConnection</EM>.
      It can supply any application-specific features that are
      appropriate, in addition to any of the profile-specific
      request header values listed below.</P>
    <P>
      Applications are not required
      to be loaded onto the device using HTTP. But if they are,
      then the
      <EM>User-Agent</EM>
      request header should be included in requests to load an
      application descriptor or application JAR file onto the
      device. This will allow the server to provide the most
      appropriate application for the device.</P>
    <P>
      The user-agent and accept-language fields SHOULD contain
      the following features as defined by system properties using
      <EM> java.lang.System.getProperty</EM>.
      If multiple values are present they will need to be reformatted
      into individual fields in the request header.</P>
    <A NAME="UserAgentHeaders"></A>
    <TABLE BORDER="2">
      <H3>
	System Properties Used for
	User-Agent and Accept-Language Request Headers</H3>
      <TR>
	<TH ROWSPAN="1" COLSPAN="1">
	  <P>
	    System Property</P>
	</TH>
	<TH ROWSPAN="1" COLSPAN="1">
	  <P>
	    Description</P>
	</TH>
      </TR>
      <TR>
	<TD ROWSPAN="1" COLSPAN="1">
	  <P>
	    <EM>microedition.profiles</EM>
	  </P>
	</TD>
	<TD ROWSPAN="1" COLSPAN="1">
	  <P>
	    A blank (Unicode U+0020) separated list of the J2ME
	    profiles that this device supports. For MIDP
	    devices, this property MUST contain at least
	    &quot;MIDP-2.0&quot;.</P>
	</TD>
      </TR>
      <TR>
	<TD ROWSPAN="1" COLSPAN="1">
	  <P>
	    <EM>microedition.configuration</EM>
	  </P>
	</TD>
	<TD ROWSPAN="1" COLSPAN="1">
	  <P>
	    The J2ME configuration supported by this device.</P>
	  <P>
	    For example, &quot;CLDC-1.0.&quot;</P>
	</TD>
      </TR>
      <TR>
	<TD ROWSPAN="1" COLSPAN="1">
	  <P>
	    <EM>microedition.locale</EM>
	  </P>
	</TD>
	<TD ROWSPAN="1" COLSPAN="1">
	  <P>
	    The name of the current locale on this device.</P>
	  <P>
	    For example, &quot;en-US.&quot;</P>
	</TD>
      </TR>
    </TABLE>

    <H4>HTTP Request Header Example</H4>
    <P>
      <EM>User-Agent: Profile/MIDP-2.1 Configuration/CLDC-1.0<BR>
	Accept-Language: en-US<BR>
      </EM>
    </P>

    <H2>StreamConnection Behavior</H2>
    
    <P>
      All MIDP <code>StreamConnections</code> have one underlying
      <code>InputStream</code> and one <code>OutputStream</code>.
      
      Opening a <code>DataInputStream</code> counts as opening an
      <code>InputStream</code> and opening a
      <code>DataOutputStream</code> counts as opening an
      <code>OutputStream</code>. 
      
      Trying to open another <code>InputStream</code> or another
      <code>OutputStream</code> from a <code>StreamConnections</code>
      causes an <CODE>IOException</CODE>.
      
      Trying to open  <code>InputStream</code> or 
      <code>OutputStream</code> after they have been closed
      causes an <CODE>IOException</CODE>.
    </P>
    
    <P>After calling the <code>close</code> method, regardless of open
      streams, further method calls to connection will result in
      <code>IOExceptions</code> for those methods that are declared to
      throw <code>IOExceptions</code>. 
      For the methods that do not throw exceptions, unknown
      results may be returned.
    </P>

    <p>
      The methods of <code>StreamConnections</code> are not
      synchronized.
      
      The only stream method that can be called safely in another
      thread is <code>close</code>. 
      
      When <code>close</code> is invoked on a stream that is executing
      in another thread, any pending  I/O method MUST throw an
      <code>InterruptedIOException</code>.  
      
      In the above case implementations SHOULD try to throw the
      exception in a timely manner. 
      
      When all open streams have been closed, and when the
      <code>StreamConnections</code> is closed, any pending I/O
      operations MUST be interrupted in a timely manner.
    </p>
    
    <H2>Secure Networking</H2>

    <p> Since the MIDP release additional  interfaces are 
      available for secure communication with WWW network
      services. Secure interfaces are provided by 
      HTTPS and SSL/TLS protocol access over the IP network.
      Refer to the package documentation of
      <CODE>javax.microedition.pki</CODE> for the details of
      certificate profile that applies to secure connections.
      An <code>HttpsConnection</code> is returned from
      <code>Connector.open()</code> when an <code>"https://"</code> connection 
      string is accessed.
      A <code>SecureConnection</code> is returned from
      <code>Connector.open()</code> when an <code>"ssl://"</code> connection 
      string is accessed.</p>

    <ul>
      <li><code>javax.microedition.io.HttpsConnection</code></li>
      <li><code>javax.microedition.io.SecureConnection</code></li>
      <li><code>javax.microedition.io.SecurityInfo</code></li>
      <li><code>javax.microedition.pki.Certificate</code></li>
      <li><code>javax.microedition.pki.CertificateException</code></li>
    </ul>

    <H2>Low Level IP Networking</H2>

    <P>
      Since the MIDP release, the MIDP specification also
      includes optional networking support for TCP/IP 
      sockets and UDP/IP datagrams. For each of the following schemes,
      a host is specified for an outbound connection and the host is omitted
      for an inbound connection.

      The host can be a host name, a literal IPv4 address or a literal
      IPv6 address (according to RFC2732 square bracket characters '['
      ']' may be used to designate an IPv6 address in URL strings).
      Implementations MUST be able to parse the URL string and
      recognize the address format used, but are not required to
      support all address formats and associated protocols.
      
    </P>
    <P>
      When the host and port number are both omitted from the <code>socket</code>
      or <code>datagram</code> connection, the system will allocate
      an available port. The host and port numbers allocated in this
      fashion can
      be discovered using the <code> getLocalAddress</code> and 
      <code>getLocalPort</code> methods. The colon (:) may be omitted when 
      the connection string does not include the port parameter.
    </P>
    <P>
      A <code>SocketConnection</code> is returned from
      <code>Connector.open()</code> when a <code>"socket://host:port"</code> 
      connection string is accessed.
      A <code>ServerSocketConnection</code> is returned from
      <code>Connector.open()</code> when a <code>"socket://:port"</code> 
      connection string is accessed.
      A <code>UDPDatagramConnection</code> is returned from
      <code>Connector.open()</code> when a <code>"datagram://host:port"</code> 
      connection string is accessed.
    </P>

    <ul>
      <li><code>javax.microedition.io.SocketConnection</code></li>
      <li><code>javax.microedition.io.ServerSocketConnection</code></li>
      <li><code>javax.microedition.io.DatagramConnection</code></li>
      <li><code>javax.microedition.io.Datagram</code></li>
      <li><code>javax.microedition.io.UDPDatagramConnection</code></li>
    </ul>
    <H2>Push Applications</H2>

    <P>
      A <code>PushRegistry</code> is available in the MIDP release
      which provides a MIDlet with a means of registering for network
      connection events, which may be delivered when the application 
      is not currently running.
    </P>

    <ul>
      <li><code>javax.microedition.io.PushRegistry</code></li>
    </ul>
    <H2>Serial Port Communications</H2>

    <P>
      A <code>CommConnection</code> is available in the MIDP release
      which provides a MIDlet with a means of registering for network
      accessing a local serial port as a stream connection.
    </P>

    <ul>
      <li><code>javax.microedition.io.CommConnection</code></li>
    </ul>
    <H2>Security of Networking Functions</H2>
    <p>The security model is found in the package
      <CODE>javax.microedition.midlet</CODE> and provides a framework
      that allows APIs and functions to be restricted to MIDlet suites
      that have been granted permissions either by signing or
      explicitly by the user. 
      (See <A HREF="../midlet/doc-files/Authorization.html">
	     Security for MIDlet suites</A>
      for details about granting specific permissions to a 
      <code>MIDlet</code> suite.)
    </p>
      
    <p>The risks associated with a MIDlet suite's use of the
      network are related the potential for network abuse
      and to costs to the device owner since network
      use may result in charges.
      MIDP provides a security framework in
      which network functions can be protected and 
      allowed only to those applications that have requested
      and been granted appropriate permissions. 
    </p>
     <p>
       Each protocol is accessed by invoking
       <CODE>javax.microedition.io.Connector.open</CODE> with a URI
       including the protocol and arguments.  The permissions below
       allow access to be granted individually to protocols. The
       functionality of the protocols is specified by subclasses of
       <CODE>Connection</CODE> interface that defines the syntax of
       the URI and any protocol specific methods.  Devices are NOT
       REQUIRED to implement every protocol. If a protocol is
       implemented, the security framework specifies the naming of
       permissions according to the package and class name of the APIs
       used to access the protocol extended with the protocol
       name. The API providing access is
       <CODE>javax.microedition.io.Connector.open</CODE>.  The table
       below defines the corresponding permissions for the protocols
       defined within this specification.
     </P>
     <TABLE WIDTH=100% BORDER=1 CELLPADDING=4 CELLSPACING=3>
       <TR VALIGN=TOP>
	 <TH WIDTH=60%>
	   <P>Permission</P>
	 </TH>
	 <TH WIDTH=40%>
	   <P>Protocol</P>
	 </TH>
       </TR>
       <TR VALIGN=TOP>
	 <TD>
	   <P><CODE>javax.microedition.io.Connector.http</CODE></P>
	 </TD>
	 <TD>
	   <P><CODE>http</CODE></P>
	 </TD>
       </TR>
       <TR VALIGN=TOP>
	 <TD>
	   <P><CODE>javax.microedition.io.Connector.https</CODE></P>
	 </TD>
	 <TD>
	   <P><CODE>https</CODE></P>
	 </TD>
       </TR>
       <TR VALIGN=TOP>
	 <TD>
	   <P><CODE>javax.microedition.io.Connector.datagram</CODE></P>
	 </TD>
	 <TD>
	   <P><CODE>datagram</CODE></P>
	 </TD>
       </TR>
       <TR VALIGN=TOP>
	 <TD>
	   <P><CODE>javax.microedition.io.Connector.datagramreceiver</CODE></P>
	 </TD>
	 <TD>
	   <P><CODE>datagram server (without host)</CODE></P>
	 </TD>
       </TR>
       <TR VALIGN=TOP>
	 <TD>
	   <P><CODE>javax.microedition.io.Connector.socket</CODE></P>
	 </TD>
	 <TD>
	   <P><CODE>socket</CODE></P>
	 </TD>
       </TR>
       <TR VALIGN=TOP>
	 <TD>
	   <P><CODE>javax.microedition.io.Connector.serversocket</CODE></P>
	 </TD>
	 <TD>
	   <P><CODE>server socket (without host)</CODE></P>
	 </TD>
       </TR>
       <TR VALIGN=TOP>
	 <TD>
	   <P><CODE>javax.microedition.io.Connector.ssl</CODE></P>
	 </TD>
	 <TD>
	   <P><CODE>ssl</CODE></P>
	 </TD>
       </TR>
       <TR VALIGN=TOP>
	 <TD>
	   <P><CODE>javax.microedition.io.Connector.comm</CODE></P>
	 </TD>
	 <TD>
	   <P><CODE>comm</CODE></P>
	 </TD>
       </TR>
     </TABLE>

     <H2><A NAME="push">Security of PushRegistry</A></H2>
     <P>The <CODE>PushRegistry</CODE> is protected using the security
       framework and permissions. The MIDlet suite must have the
       <CODE>javax.microedition.io.PushRegistry</CODE> permission to
       register an alarm based launch, to register dynamically using
       the <CODE>PushRegistry</CODE>, to make a static registration
       in the application descriptor and to determine if the user
       needs to be prompted prior to invoking MIDlet suite
       in response to a Push connection event or alarm.
       <A HREF="../midlet/doc-files/Authorization.html#domain">
       The protection domain</A> defines the general behavior for user
       permissions with the interaction modes of "oneshot", "session",
       and "blanket". For the <CODE>PushRegistry</CODE> and the AMS,
       launching behavior is specialized:
     </P>
     <UL>
     <LI>Oneshot: The user is prompted before the MIDlet suite is
       invoked to handle a push event or alarm and for each
       <CODE>PushRegistry</CODE> request; for example to register
       an alarm or a connection.</LI>

     <LI>Session: The user is prompted before the MIDlet suite is
       invoked to handle a push event or alarm, or before the first
       <CODE>PushRegistry</CODE> request; for example to register
       an alarm or a connection.  Subsequently, when a MIDlet uses the
       <CODE>PushRegistry</CODE> the user is not prompted.</LI>

     <LI>Blanket: The user is prompted only once during installation,
       before the first time the MIDlet suite is invoked to handle a
       push event or alarm, or uses the <CODE>PushRegistry</CODE>.</LI>
     </UL>

     <P>The push mechanism uses protocols in which the device is
       acting as the server and connections can be accepted from other
       elements of the network. To use the push mechanisms the MIDlet
       suite will need the permission to use the server connection.

       For example, to register a chat program that can be started via
       push might use the following attributes in the manifest:</P>

     <PRE>
MIDlet-Push-1: socket://:79, com.sun.example.SampleChat, *
MIDlet-Permissions: javax.microedition.io.PushRegistry, javax.microedition.io.Connector.serversocket
     </PRE>

    @since MIDP 1.0
  </body>
</html>

